Vibe Audit_01_답답해서 만들어본 에이전트 감사 도구

GitHub: Vibe-Audit

바이브코딩의 맥락 전환 문제

요즘은 대부분 AI 에이전트를 써서 코딩을 한다. Claude Code, Gemini CLI, Codex CLI 같은 도구들 말이다.
나도 꽤 오래 쓰고 있고 생산성도 확실히 올랐다.

분명히 느끼는 것은, 오늘 경험하는 AI가 가장 구리다는 말처럼
시간이 지날 수록 AI가 엄청나게 발전하는 것이 몸으로 느껴진다.

그럼에도 불구하고 아직 아쉬운 점이 많은데, 에이전트의 맥락 유지 문제이다.
Claude도, Gemini도, OpenAI도 이 문제를 다양한 방법으로 해결한다.
콘텍스트 캐싱, 요약, 계층적 메모리, 툴 사용 등등....
이 문제만 연구하는 학자도 있고, 아무튼 우리가 지금처럼 AI로 편한 개발 환경을 누리는 것은 이런 문제들을 깊이 연구하는 사람들 덕분이기도 하다.

그러나 여전히 가끔, 아니 자주 에이전트가 내 의도를 유지하지 못하는 순간을 맞이한다.
그럴 때마다 새 대화를 켜거나.... 아니면 또 다른 편리한 도구를 사용하곤 한다.
이런 콘텍스트 스위칭(Context switching) 문제는 이미 오래 전부터 해결책이 우후죽순으로 쏟아져 나오곤 했다.

하지만 내가 겪은 진짜 문제는 '조용한 전환'이다. 뭔가 번역투 같은데.
아무튼 에이전트가 내 의도에서 벗어나는 것을 개발자가 알아차리지 못하고 계속 진행하는 것 말이다.

예를 들어 다음과 같은 것들이 있다.

• 에이전트가 맥락을 압축하는 과정에서 이전에 되돌린 작업을 재수행
• 에이전트가 미처 지우지 못한 주석을 읽고 엉뚱한 방향으로 수정
• 에이전트가 새 기능을 덧붙이면서 이전에 취소한 작업을 다시 수행
  등등... 알아챘을 때는 이미 한참 잘못된 방향으로 진행된 뒤다.

이런 현상을 막기 위해 전 GitHub CEO인 Thomas Dohmke는 Entire AI 같은 플랫폼을 만들기도 했다.
AI의 내러티브를 유지하며 체크포인트를 통해 깃허브처럼 사용하면서 추론 과정을 확인하고, 효율적인 토큰을 사용하게끔 하는 등....

이런 유명 개발자의 대형, 상용 프로젝트를 따라가는 건 뱁새-황새 꼴이다.
그래서 나는 그냥 내가 답답한 부분을 해결해보고 싶어서, 내 작업을 망치지 않기 위해서 로컬 관측 도구를 만들어보고자 했다.

처음에는 나도 더 잘 만들어주는 에이전트나 도구를 찾아다녔다. 프롬프트를 다듬고 스킬을 붙이고 도구를 바꿔가며 써봤다.
하지만 에이전트를 더 똑똑하게 만드는 건 내 영역이 아니다.

그래서 그냥 내가 잘 하는 것을 해보려고 했다.
지금 에이전트의 작업이 원래 의도에서 벗어나지 않았는지 판단할 수 있는 도구를 만드는 것이다.
맥락을 읽고 이해하는 것이나 이전의 여러 맥락과 연결짓는 것은 도서 편집자의 기본 소양이고, 난 이 훈련이 아주 잘 되어 있다고 생각한다.

아무튼 그래서 감사(Audit)라는 방향을 잡아봤다. 에이전트를 막거나 컨트롤하는 도구가 아니라 그냥 상태를 보여주는 도구,
완벽한 정답을 AI가 알아서 딱딱 해주는 것이 아니라 사람이 언제 개입할지 타이밍을 알아보는 도구 말이다.

설계해보기

기획 단계에서 이 도구가 답해야 할 세 가지 질문을 던졌다.

1. 지금 에이전트의 작업이 처음에 에이전트에게 묻고 계획한 의도와 얼마나 맞는가?
2. 이 변화는 기존 흐름과 연속되는가 아니면 새로운 국면인가, 그것도 아니면 방향이 전환됬는가?
3. 그렇게 판단한 근거가 뭔가?

기능도 자연스럽게 이 질문들을 중심으로 붙었다.

• Baseline 자동 생성: 첫 사용자 메시지에서 의도를 추출해 기준선 설정
• Phase Shift 분류: continuation / new_phase / pivot 세 가지로 턴마다 분류
• Alignment Score: 정렬 점수와 함께 "왜 이 점수인지" 근거를 제시
• Dual Flag: 규칙 기반 신호 + LLM 기반 분석을 분리
• Context Evolution / Event Log: 맥락 변화 이력 추적

스택은 백엔드 FastAPI + SQLite, 프론트는 React로 잡았다.
Vibe-kanban을 보고 영감을 얻은지라, 로컬에서만 작동하게 하면 좋겠다 싶었다.

CLI 훅(Claude Code, Gemini CLI, Codex CLI)으로 대화를 수집하고 백엔드에서 분석한 뒤 웹 UI로 보여주는 구조다.
이번 기회에 npm 배포까지 해봐서 npx vibe-audit 한 줄로 로컬에서 바로 띄워보자! 생각했다.